Data Transfer

Inside Macintosh: OpenDoc Class Reference / Part 2 - Types and Constants

Data Transfer
This section describes the types and constants used during data-transfer operations.

General
The following types and constants are used frequently in data-transfer operations.

ODUpdateID
A 32-bit value used as an update identifier for clipboard content or linked content. Two ODUpdateID values associated with different versions of the same content may be tested for equality, but any other use of these values is meaningless.
Constants of this type

kODUnknownUpdate
A value guaranteed to be different from any actual update ID. This constant can be used by parts when the update ID associated with shared content is unknown.

ODCloneKind
An enumeration specifying the possible semantic values of a clone operation.
Constants of this type

kODCloneCopy
Copy to the clipboard object or the drag-and-drop object.
kODCloneCut
Cut to the clipboard object or the drag-and-drop object.
kODCloneDropCopy
Copy at the destination of a drop.
kODCloneDropMove
Move at the destination of a drop.
kODCloneFromLink
Clone from a link.
kODClonePaste
Paste from the clipboard object.
kODCloneToLink
Clone to a link source.

ODPasteAsMergeSetting
A 32-bit value used to specify which At the Destination radio button (Merge with Contents or Embed As) is initially selected in the Paste As dialog box and whether the other button is available.
Constants of this type

kODPasteAsEmbed
Embed As is initially selected; Merge with Contents is available.
kODPasteAsEmbedOnly
Embed As is selected; Merge with Contents is disabled.
kODPasteAsMerge
Merge with Contents is initially selected; Embed As is available.
kODPasteAsMergeOnly
Merge with Contents is selected; Embed As is disabled.

ODPasteAsResult
A structure representing the user's selections in the Paste As dialog box.
            struct ODPasteAsResult {
               ODBoolean      pasteLinkSetting;
               ODBoolean      autoUpdateSetting;
               ODBoolean      mergeSetting;
               ODTypeToken    selectedView;
               ODType         selectedKind;
               ODType         translateKind;
               ODEditor       editor;
            };
Field descriptions

pasteLinkSetting
kODTrue if a link was chosen, otherwise kODFalse.
autoUpdateSetting
kODTrue if automatic updating was chosen, otherwise kODFalse. Relevant only if pasteLinkSetting is kODTrue.
mergeSetting
kODTrue if incorporation was chosen; kODFalse if embedding was chosen.
selectedView
The view type chosen. This field contains the tokenized form of a view-type constant (page 883). You can call the session object's GetType method (page 611) to convert the token into the corresponding view type.
selectedKind
The part kind chosen for merging.
translateKind
If data translation was chosen, this field indicates the available type that should be translated to selectedKind. If an available kind was chosen, this field is kODNULL.
editor
The preferred editor to bind to the part after embedding; kODNoEditor if no specific editor was chosen. Relevant only if mergeSetting is kODFalse.
ODPlatformType
A 32-bit wrapper for the platform-specific type used to identify data formats for data interchange. On the Mac OS, this type is identical to the ScrapType or OSType types (a four-character code).

The following constant is used for clipboard and linking operations.

Translation
The following types and constants are used during translation of part data from one part kind to another.

ODPlatformTypeSpace
A 32-bit value used to specify the type of a platform-specific structure identifying a type space (data or file).
Constants of this type

kODPlatformDataType
The native operating system scrap type.
kODPlatformFileType
The native operating system file type.

ODTranslateResult
An enumeration specifying the possible results of a translation.
Constants of this type

kODCannotTranslate
Translation is not allowed with the given types.
kODCanTranslate
Translation is allowed with the given types.

Drag and Drop
This section describes the types and constants used for drag-and-drop operations. Types and constants marked [M] are specific to the Mac OS platform.

ODPlatformDragReference [M]
A 32-bit value identifying the current drag operation.

The following constant of type ODType (page 876) can be passed as a parameter to the StartDrag method (page 195) of the drag-and-drop object to specify the type of image OpenDoc should display to the user as dragging feedback.

kODDragImageRegionHandle [M]
The drag image is a handle to a drag region, as required by the Mac OS Drag Manager.

Drag Attributes
The following constants of type ODULong (page 878) are used to represent bit flags that can be set in the drag attributes of a particular drag-and-drop operation. You can inspect the drag attributes by calling the GetDragAttributes method (page 191) of the drag-and-drop object; test the returned value for the presence of a particular flag using the bitwise AND operator (for example, the & operator in C++). Some flags are relevant to a part tracking a drag event that has entered one of its facets; others are relevant to the part that is the destination of a drop.
Drag-tracking flags

kODDragIsInSourceFrame
The user has not left the source frame.
kODDragIsInSourcePart
The user has not left the source part.
Drop flags

kODDropIsInSourceFrame
The drop is occurring in the source frame of the drag.
kODDropIsInSourcePart
The drop is occurring in the same part as the source frame of the drag.
kODDropIsMove
The drag-and-drop operation is a move.
kODDropIsCopy
The drag-and-drop operation is a copy.
kODDropIsPasteAs
The destination part should display the Paste As dialog box.

Result Types
The following types and constants represent the results of drag-and-drop operations.

ODDragResult
A result of type ODBoolean (page 878) indicating whether a drop is allowed in the specified facet.
ODDropResult
An enumeration specifying the result of a drop operation.
Constants of this type

kODDropCopy
Successful synchronous drop with copy semantics.
kODDropFail
Unsuccessful synchronous drop.
kODDropMove
Successful synchronous drop with move semantics.
kODDropUnfinished
An asynchronous drag-and-drop operation was started.

Asynchronous dragging is not currently supported on the Mac OS platform.

Linking
The following types and constants are used in linking operations.

ODLinkInfo
A structure that contains information about a link destination for display in the Link Destination Info dialog box.
            struct ODLinkInfo {
               ODType         kind;
               ODTime         creationTime;
               ODTime         changeTime;
               ODUpdateID     change;
               ODBoolean      autoUpdate;
            };
Field descriptions

kind
The part kind used by the link destination.
creationTime
The date and time when this link destination was created.
changeTime
The date and time of the latest source update read by this destination.
change
The update ID of the latest source update read by this destination.
autoUpdate
kODTrue if this destination updates automatically, otherwise kODFalse.
ODLinkInfoAction
An enumeration specifying the kind of action to be taken as the result of user selections in either the Link Source Info dialog box or the Link Destination Info dialog box.
Constants of this type

kODLinkInfoBreakLink
Break the link.
kODLinkInfoCancel
Take no action; the user canceled the dialog box.
kODLinkInfoFindSource
Display the source of the link. Relevant only in the Link Destination Info dialog box.
kODLinkInfoOk
Accept any new settings selected by the user in the dialog box.
kODLinkInfoUpdateNow
Update the link immediately.
ODLinkInfoResult
A structure that contains the results of user selections in either the Link Source Info dialog box or the Link Destination Info dialog box.
            struct ODLinkInfoResult {
               ODLinkInfoAction  action;
               ODBoolean         autoUpdate;
            };
Field descriptions

action
The action taken by the user to dismiss the dialog box.
autoUpdate
kODTrue if the user chose automatic updating, otherwise kODFalse.
ODLinkKey
An opaque 32-bit type used to provide thread-safe access to link content. A link key is created when a link object or link-source object is locked; the link key must be used in any method that returns or modifies the content storage unit of the locked link object or link-source object.